Summary

Follow-up to #251 addressing the post-merge audit from @scr-oath, plus additional hardening from a code-review / security-review pass.

What changed

Correctness

• Ordering fix (a2a.py): _context_id and _active_task_id commit only after _process_task_response and the idempotency-error check both succeed. A raise from either previously left the adapter advanced to a response the caller never saw, potentially orphaning the in-flight task on retry.
• Empty-string guard (client.py): context_id="" from os.getenv(...) or "" patterns is now treated as "not provided" instead of being seeded on the wire.
• unknown TaskState: explicit — clears active_task_id and logs a warning.

API shape

• Rename: pending_task_id → active_task_id (public on ADCPClient + A2AAdapter, and internal _pending_task_id). The old name read as "queued, not yet sent"; the real semantic is "server-side task the next call must echo to resume."
• Checkpoint API:

  state: Checkpoint = client.checkpoint()
  # persist state (e.g. Redis)
  client = ADCPClient.from_checkpoint(agent_config, state)

  Checkpoint is a TypedDict carrying agent_id, context_id, active_task_id. Fixes the Redis-resume story for HITL flows — persisting only context_id would orphan the pending task. from_checkpoint rejects mis-matched agent_id (Agent A's checkpoint restored onto Agent B would leak session ids to a different vendor).
• Exception type: ValueError → TypeError on non-A2A context_id= / reset_context() / from_checkpoint(active_task_id=...). The string value is fine; the operation doesn't apply to non-A2A.

Internals

• _NONTERMINAL_TASK_STATES: frozenset[TaskState] — coupled to the a2a.types.TaskState enum so an upstream rename becomes a type error, not a silent retention regression.
• A2AAdapter._restore_active_task_id() — narrow internal setter used only by from_checkpoint so rename-safety fails loudly.

Coverage

• Unit tests for every non-terminal retain (submitted, working, input-required, auth-required) and every terminal clear (completed, failed, canceled, rejected, unknown).
• Two tests pinning the ordering invariant: one for the IdempotencyConflictError propagation path, one for the converted-to-TaskResult(FAILED) path.
• Tests for checkpoint() round-trip, agent_id mismatch rejection, and non-A2A active_task_id rejection.

Breaking changes

1. ADCPClient.pending_task_id → ADCPClient.active_task_id (same for A2AAdapter).
2. ADCPClient(context_id=...) / reset_context() raise TypeError (was ValueError) on non-A2A.

Both pre-GA; callers catching ValueError or reading pending_task_id must update.

Test plan

• ruff check src/ — clean
• mypy src/adcp/ — 679 files, clean
• pytest tests/test_protocols.py — 70/70 pass
• pytest tests/integration/test_a2a_context_id.py — 5/5 pass (real uvicorn-hosted a2a-sdk Starlette app)
• Full non-integration suite — 2069 passed, 21 skipped (baseline 2065 + 4 new state-transition tests)
• Independent code-review + security-review passes; all SHOULD FIX items addressed

🤖 Generated with Claude Code